<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>throw: common_schema documentation</title>
	<meta name="description" content="throw: common_schema" />
	<meta name="keywords" content="throw: common_schema" />
	<link rel="stylesheet" type="text/css" href="css/style.css" />
</head>

<body>
	<div id="main">
		<div id="header">
			<h1>common_schema</h1> <strong>2.2</strong> documentation
			<div class="subtitle">DBA's framework for MySQL</div>
		</div>
		<div id="contentwrapper">
			<div id="content">
				<h2><a href="throw.html">throw</a></h2>	
<h3>NAME</h3>
throw(): Disrupt execution with error

<h3>TYPE</h3>
Procedure

<h3>DESCRIPTION</h3>
<p>
Issues an error at the point of invocation, providing with an error message.
</p>

<p>
	This is done by invoking an invalid command on the server. The result of such invocation will
	break execution of calling code. If this routine is invoked from another routine, the entire
	call stack is aborted. If this routine is called during a transaction, the transaction aborts
	and rolls back.
</p>
<p>
	On a MySQL >= <strong>5.5</strong> server this routine calls upon <strong>SIGNAL</strong>.
	On a <strong>5.1</strong> server it generates a statement which reads from an invalid table,
	producing an awkward yet informative error message.
</p>

<h3>SYNOPSIS</h3>
<p>
<blockquote><pre>throw(error_message VARCHAR(1024) CHARSET utf8)
  NO SQL</pre></blockquote>
</p>
<p>
  Input:
  <ul>
    <li><strong>error_message</strong>: a message to be displayed within error statement.</li>
  </ul>
</p>
<p>
  Output:
  <ul>
    <li><strong>@common_schema_error</strong>: The procedure sets this variable to the error_message supplied.</li>
  </ul>
</p>

<h3>EXAMPLES</h3>
	<p>
		Invoke <i>throw()</i> directly, on a <strong>5.1</strong> MySQL server:
	</p>
	<blockquote><pre>mysql&gt; call throw('Unknown variable type');
ERROR 1644 (91100): Unknown variable type

mysql&gt; SELECT @common_schema_error;
+-----------------------+
| @common_schema_error  |
+-----------------------+
| Unknown variable type |
+-----------------------+
</pre></blockquote>
	<p>
		Invoke <i>throw()</i> directly, on a <strong>5.1</strong> MySQL server:
	</p>
	<blockquote><pre>mysql&gt; call throw('Unknown variable type');
ERROR 1146 (42S02): Table 'error.Unknown variable type' doesn't exist
</pre></blockquote>

	<p>
		Invoke a syntactically invalid script; the <a href="run.html">run()</a> routine
		and subroutines validate script syntax and call upon <i>throw()</i>:
	</p>
	<blockquote><pre>mysql&gt; call run('{set @x := 3; ; ; }');
ERROR 1103 (42000): Incorrect table name 'QueryScript error: [Empty statement not allowed. Use {} instead] at 16: "; ; }"'

mysql&gt; SELECT @common_schema_error;
+---------------------------------------------------------------------------------+
| @common_schema_error                                                            |
+---------------------------------------------------------------------------------+
| QueryScript error: [Empty statement not allowed. Use {} instead] at 16: "; ; }" |
+---------------------------------------------------------------------------------+
</pre></blockquote>


<h3>ENVIRONMENT</h3>
MySQL 5.1 or newer

<h3>AUTHOR</h3>
Shlomi Noach
				<br/>
			</div>
			<div id="sidebarwrapper">
				<div id="search">
					Search online documentation
					<form id="search_form" name="search_form" method="GET" 
						action="http://www.google.com/search" 
						onsubmit="document.forms['search_form']['q'].value = 'site:http://common-schema.googlecode.com/svn/trunk/common_schema/doc/html/ '+document.forms['search_form']['search_term'].value;">
						<input type="text" name="search_term" value=""/>
						<input type="hidden" name="q" value=""/>
						<input type="submit" value="go"/>						
					</form>
				</div>
				<div id="menu">
					<ul>
						<li><a title="Introduction" href="introduction.html">Introduction</a></li>
						<li><a title="Documentation" href="documentation.html">Documentation</a></li>
						<li><a title="Download" href="download.html">Download</a></li>
						<li><a title="Install" href="install.html">Install</a></li>
						<li><a title="Risks" href="risks.html">Risks</a></li>
					</ul>						
					<h3>QUERY SCRIPT</h3>
					<ul>
						<li><a title="QueryScript" href="query_script.html">QueryScript</a></li>
						<li><a title="Execution" href="query_script_execution.html">Execution</a></li>
						<li><a title="Flow control" href="query_script_flow_control.html">Flow control</a></li>
						<li><a title="Statements" href="query_script_statements.html">Statements</a></li>
						<li><a title="Expressions" href="query_script_expressions.html">Expressions</a></li>
						<li><a title="Variables" href="query_script_variables.html">Variables</a></li>
					</ul>						
					<h3>DEBUG</h3>
					<ul>
						<li><a title="rdebug" href="rdebug.html">rdebug</a></li>
						<li><a title="rdebug API" href="rdebug_api.html">rdebug API</a></li>
						<li><a title="rdebug workflow" href="rdebug_workflow.html">Workflow</a></li>
					</ul>						
					<h3>ROUTINES</h3>
					<ul>
						<li><a title="Execution &amp; flow control" href="execution_routines.html">Execution & flow control</a></li>
						<li><a title="General" href="general_routines.html">General</a></li>
						<li><a title="Process" href="process_routines.html">Process</a></li>
						<li><a title="Query analysis" href="query_analysis_routines.html">Query analysis</a></li>
						<li><a title="Schema analysis" href="schema_analysis_routines.html">Schema analysis</a></li>
						<li><a title="Security" href="security_routines.html">Security</a></li>
						<li><a title="Text" href="text_routines.html">Text</a></li>
						<li><a title="Time &amp; date" href="temporal_routines.html">Time & date</a></li>
						<li><a title="Charting" href="charting_routines.html">Charting</a></li>
					</ul>
					<h3>VIEWS</h3>
					<ul>
						<li><a title="Schema analysis" href="schema_analysis_views.html">Schema analysis</a></li>
						<li><a title="Data dimension" href="data_dimension_views.html">Data dimension</a></li>
						<li><a title="Process" href="process_views.html">Process</a></li>
						<li><a title="Security" href="security_views.html">Security</a></li>
						<li><a title="Monitoring" href="monitoring_views.html">Monitoring</a></li>
						<li><a title="InnoDB Plugin" href="innodb_plugin_views.html">InnoDB Plugin</a></li>
						<li><a title="Percona server" href="percona_server_views.html">Percona Server</a></li>
						<li><a title="TokuDB" href="tokudb_views.html">TokuDB</a></li>
					</ul>						
					<h3>DATA</h3>
					<ul>
						<li><a title="tables" href="tables.html">Tables</a></li>
						<li><a title="variables" href="variables.html">Variables</a></li>
					</ul>						
					<h3>META</h3>
					<ul>
						<li><a title="Help" href="help.html">help</a></li>
						<li><a title="Metadata" href="metadata.html">metadata</a></li>
						<li><a title="status" href="status.html">status</a></li>
					</ul>						
				</div>
			</div>	
			<div class="clear">&nbsp;</div>
			
			<div id="footnote" align="center">
				<a href="">common_schema</a> documentation
			</div>
		</div>
	</div>
</body>
</html>
